Changing Monitor Settings

The monitoring functionality in RTX64 allows you to trace the behavior of your real-time applications by recording significant events that occur during execution of those applications. The events are written to disk, where they are grouped into sessions. Each session corresponds to a single folder that contains one or more files containing events generated during that session. A new session begins each time monitoring is started, and the current session ends each time monitoring is stopped. You can view and analyze session data in Tracealyzer.

On the Change monitor settings page in RTX64 Control Panel, you can specify the global, persistent default monitoring settings you want to use when the Subsystem is started.

NOTE: You can configure the overall amount of non-paged memory that the Subsystem will dedicate to collecting monitored events through the Manage memory page in RTX64 Control Panel.

NOTE: Monitoring causes as much as one microsecond of latency depending on the real time operation. It is recommended that you only enable and start monitoring during development and that you disable monitoring in production. The amount of latency depends on how many kinds of events are being monitored and how frequently those events occur in real-time applications. Monitoring fewer kinds of events reduces the impact of monitoring on latency.

NOTE: RTX64 collects additional monitoring session data to support collection of pre-start-trigger events. See Customizing Session Collection Behavior below.

Sections in this topic:

Opening this Page in RTX64 Control Panel
Enabling and Optionally Auto-Starting Monitoring
Configuring Events to Collect by Default
Configuring Session Collection Behavior
Configuring Session Logging
Configuring Stop Behavior when the Event Count, Session, or Disk Size is Reached

Opening this Page in RTX64 Control Panel

To open this page in the Control Panel:

In the Start menu, navigate to RTX64 4.5 Runtime and click RTX64 Control Panel.
Click Configure the RTSS Subsystem > Change Monitoring settings.

Enabling and Optionally Auto-starting Monitoring

Monitoring can be in one of four states: disabled, enabled, started, or paused. Monitoring is disabled by default. Two check boxes determine the state of monitoring when the Subsystem starts:

Enable instrumentation within the Subsystem for monitoring real-time applications: Select this check box to enable monitoring when the RTX64 Subsystem starts and until the Subsystem is stopped again.

NOTE: Enabling does not start monitoring. It only performs the required system setup and preparation, which includes allocating non-paged pool memory dedicated to monitoring. It also introduces additional subsystem activity to support pre-trigger events.

If selection of this check box is cleared, when you start monitoring from RTX64 Monitor, you will be warned that doing so will cause a momentary loss of determinism as monitoring passes from disabled to enabled state before starting. Once monitoring is enabled, you can use RTX64 Monitor to dynamically start, stop, and pause monitoring, adjust the events you want to monitor, and convert the binary files in session folders into text files.

Use Subsystem start as a trigger to start a session: This check box is not selectable until you enable instrumentation. Once you enable instrumentation, you can specify that a new monitoring session starts automatically when the Subsystem starts. If you leave this check box cleared, you must manually start the monitoring session using RTX64 Monitor, either of the real-time APIs RtMonitorControl or RtMonitorChangeState, or by setting an event to act as a start trigger.

RTX64 4.3 and Later

Under Configure events to collect by default, you can define the default set of events to collect in a monitor session. You can manually choose events to collect or select one of the predefined sets of events, such as Collect memory events, to only collect events specific to that area of focus.

To configure events to collect:

Expand the Configure events to collect by default section.
Choose an option:

Option	Description
Collect performance-related events	Collects a predefined set of performance-related events from these event groups: Exceptions Fast Semaphores General Object Events General System Events Real-time Processes Real-time Threads Timers
Collect memory events	Collects a predefined set of memory-related events from these event groups: Heaps Memory
Collect deadlock/synchronization events	Collects a predefined set of deadlock and synchronization-related events from these event groups: Critical Sections Events Fast Semaphores Mutexes Real-time Threads Semaphores
Collect custom events	Collects all custom events. Custom events are generated by the API RtGenerateEvent.
Allow me to choose	Manually select the events you want collect: Select an event to include it in a monitor session. Select an event group to select all events within that group. Clear selection of an event to exclude it from a session. Clear selection of an event group to clear all events within that group.

NOTE: To always monitor network-related events, such as Network Abstraction Layer (NAL) and RT-TCP/IP Stack events, select the check box Include network events. When selection of this check box is cleared, network-related events will not be collected, unless they are dynamically included in event collection on a per-session basis through RTX64 Monitor.

NOTE: Once monitoring is enabled, changes to the events selected in the Control Panel will not take effect until you restart the Subsystem.

See Event Classes for an alphabetical listing of all monitor events.

RTX64 4.2 and Earlier

Under Configure events to collect by default, you can define the default set of events to collect in a monitor session.

To configure events to collect:

Select an event to include it in a monitor session. Select an event group to select all the events within that group.
Clear selection of an event to exclude it from a session. Clear selection of an event group to clear all events within that group.

NOTE: Most events are selected by default, with the exception of events that are extremely verbose, such as context switches, which can potentially generate many thousands of events per second per core, depending on the value of the HAL timer period.

NOTE: To always monitor network-related events, such as RT-TCP/IP Stack events, select the check box Include network events. When selection of this check box is cleared, network-related events will not be collected, unless they are dynamically included in event collection on a per-session basis through RTX64 Monitor.

NOTE: Once monitoring is enabled, any changes to the events selected in the Control Panel do not take effect until you restart the Subsystem.

There are two real-time APIs related to events:

Use RtGenerateEvent to create custom events to instrument your own code.
Use RtMonitorControl to programmatically enable/disable events or start/stop monitoring.

Customizing Session Collection Behavior

Under Customize session collection behavior, you can set the maximum number of events to collect and determine whether you would like to collect pre-start-trigger events.

Setting	Description	Action
Maximum number of events to collect	Configures the maximum number of events to collect in a monitor session.	Select a radio button: Unlimited – choose this option to collect events until the monitoring session is manually stopped. This is the default option. Only collect this many events – specify a value for the maximum number of events to collect during a monitor session. This value must be greater than 0. The default value is 20,000 events.
Number of pre-start-trigger events to collect	Configures the number of pre-start-trigger events, if any, to collect. Pre-start-trigger events are events that occur before the event that triggers the start of a monitoring session.	Specify a value for the number of pre-start-trigger events to collect during a monitor session. The default value is 0 events (no pre-start-trigger events collected). NOTE: When Maximum number of events to collect is set to Only collect this many events, the number of pre-start-trigger events to collect must not exceed it. NOTE: Some pre-start-trigger events may be lost if the start trigger event is set and subsequently triggered within several milliseconds of the end of a previous monitoring session. NOTE: RTX64 collects additional monitoring session data to support collection of pre-start-trigger events.

Setting

Description

Action

Maximum number of events to collect

Configures the maximum number of events to collect in a monitor session.

Select a radio button:

Unlimited – choose this option to collect events until the monitoring session is manually stopped. This is the default option.
Only collect this many events – specify a value for the maximum number of events to collect during a monitor session. This value must be greater than 0. The default value is 20,000 events.

Number of pre-start-trigger events to collect

Configures the number of pre-start-trigger events, if any, to collect. Pre-start-trigger events are events that occur before the event that triggers the start of a monitoring session.

Specify a value for the number of pre-start-trigger events to collect during a monitor session. The default value is 0 events (no pre-start-trigger events collected).

NOTE: When Maximum number of events to collect is set to Only collect this many events, the number of pre-start-trigger events to collect must not exceed it.

NOTE: Some pre-start-trigger events may be lost if the start trigger event is set and subsequently triggered within several milliseconds of the end of a previous monitoring session.

NOTE: RTX64 collects additional monitoring session data to support collection of pre-start-trigger events.

Customizing Session Logging

Under Customizing session logging, you can configure where monitor session logs are saved and a maximum value for the log size and disk space allowed.

Setting Description Action

Setting	Description	Action
Location of Session Logs	The location to which session logs are saved. The default location is `C:\ProgramData\IntervalZero\Monitor`	To change the default, click Browse and select a new location. NOTE: The path you choose cannot be on a mapped drive and it cannot be a UNC path name. NOTE: This file path cannot exceed 200 characters.
Maximum session log size on disk (megabytes)	The maximum value, in megabytes, of a single monitoring session folder.	Drag the slider or enter a new value in the text entry field. The default value is 200MB. NOTE: RTX64 displays a warning message in these scenarios: • When the log folder size might exceed the available disk space on the system. • When the monitoring log folder is nearly full. • When this value exceeds the Maximum disk space allowed value. Hover the mouse cursor over the warning icon to view information in a tooltip.
Maximum disk space allowed (megabytes)	The maximum amount, in megabytes, of disk space allowed for all monitoring session folders.	Drag the slider or enter a new value in the text entry field. The default is 10% of free disk space. NOTE: The <disk space> remaining label updates dynamically to show the amount of the Maximum disk space allowed value that has not been used. If the value in this label exceeds the amount of free disk space, a warning appears. Hover the mouse cursor over the warning icon to view information in a tooltip.

Location of Session Logs

The location to which session logs are saved. The default location is C:\ProgramData\IntervalZero\Monitor

To change the default, click Browse and select a new location.

NOTE: The path you choose cannot be on a mapped drive and it cannot be a UNC path name.

NOTE: This file path cannot exceed 200 characters.

Maximum session log size on disk (megabytes)

The maximum value, in megabytes, of a single monitoring session folder.

Drag the slider or enter a new value in the text entry field. The default value is 200MB.

NOTE: RTX64 displays a warning message in these scenarios:

• When the log folder size might exceed the available disk space on the system.

• When the monitoring log folder is nearly full.

• When this value exceeds the Maximum disk space allowed value.

Hover the mouse cursor over the warning icon to view information in a tooltip.

Maximum disk space allowed (megabytes)

The maximum amount, in megabytes, of disk space allowed for all monitoring session folders.

Drag the slider or enter a new value in the text entry field. The default is 10% of free disk space.

NOTE: The <disk space> remaining label updates dynamically to show the amount of the Maximum disk space allowed value that has not been used. If the value in this label exceeds the amount of free disk space, a warning appears. Hover the mouse cursor over the warning icon to view information in a tooltip.

Configuring Stop Behavior when the Event Count, Session, or Disk Size is Reached

You can configure the stop behavior of a monitoring session when any of the below scenarios is reached:

The maximum number of events to collect is reached
The maximum session folder size is reached
The maximum disk space allowed is reached

Setting	Description	Action
Automatic (stop collecting)	Configures monitoring to stop automatically in any of the above scenarios. This is the default setting.	Select the radio button.
Manual (continue collecting and discard oldest events until stopped)	Configures monitoring to continue collecting events until manually stopped. In this configuration, the oldest events in the session are discarded to make room for the most recent events collected until monitoring is stopped.	Select the radio button.